Skip to content

feat: onboarding Phase 1: .sctx.json discovery, setup-space, session preflight - #175

Merged
mindsocket merged 17 commits into
mainfrom
feat/onboarding-phase1
Oct 27, 2026
Merged

mindsocket merged 17 commits into
mainfrom
feat/onboarding-phase1

Conversation

@mindsocket

Copy link
Copy Markdown
Owner

Refs #145. Phase 1 of the onboarding journey: from "installed the Claude Code plugin" to a configured space and a first agent edit that stays valid, for someone with an existing folder or Obsidian vault.

What changes

Config discovery (breaking)

  • The config is found from --config, then $SCTX_CONFIG, then the nearest .sctx.json walking up from the working directory, then the global file. Nearest wins and nothing is merged by location.
  • A local config is no longer shadowed by a global one.
  • The working-directory ./config.json lookup is removed. Rename it to .sctx.json or set SCTX_CONFIG.
  • Paths in a config resolve against the folder holding it, so "path": "." is the whole vault.
  • includeSpacesFrom: a space in the including file overrides an included space of the same name instead of throwing; later includes override earlier ones; a leading ~ is expanded; a missing include reports E_INCLUDE_NOT_FOUND.

sctx spaces

  • Reports the config used, how it was found, and problems with stable codes (E_CONFIG_NOT_FOUND, E_SPACE_PATH_MISSING, E_SCHEMA_NOT_FOUND, ...), each with a fix. --json includes them. Exits 1 on an error; a missing config with nothing set is info and exits 0.
  • sctx spaces add <name> <path> --schema <file> writes to the config found by walking up, or the one named by --config. When discovery would land on the global file or on nothing it requires --config <folder>/.sctx.json or --global. It will not rewrite a file with comments or trailing commas (prints the entry instead), and rejects a schema that does not resolve.
  • addSpace and checkConfig are exported from structured-context/api for other hosts.

Claude Code plugin

  • New SessionStart hook runs sctx spaces --json for the session folder. It reports a broken setup once, with a code, and tells the agent which spaces apply when healthy. It says nothing when no config exists.
  • The other hooks treat an unusable answer as "no spaces", stay silent, and pick the config up again as soon as it is fixed. An unexpected hook error becomes one E_HOOK_FAILED message per session with exit 0 instead of a bare exit 1. Only new validation errors in the Stop hook still block.
  • A shell guard reports a missing Bun (E_NO_BUN) and keeps the other hooks quiet.
  • The CLI is run from the session folder, using an installed sctx if there is one, otherwise bunx pinned to the plugin's major.minor.
  • New setup-space skill and /setup-space command: look at the content by sampling, propose one space, write it with sctx spaces add, summarise the validation gap, make a guided first edit. The structured-context skill gains references/troubleshooting.md, one row per error code.

Verification

  • bun test: 909 pass, 0 fail; typecheck and lint clean.
  • Ran claude -p with this plugin against copies of three real vaults. A strategy-tree vault and a mixed inbox were set up and edited validly; the hooks ran silently. A 279-note playbook vault had no fitting bundled schema, the agent wrote its own and hit the turn cap; the skill now stops and explains instead.
  • measured: a cold bunx structured-context@0.14.0 --version with an empty cache took 2.2s and a warm one 0.16s, against the 30s prompt-hook cap (one run, one network).

Not in this PR

  • Hooks finding a config from the edited file's path when the session starts above it.
  • Commands to edit or remove a space.
  • Map view and starting from a template.
  • Obsidian plugin support is on a separate branch of obsidian-structured-context and needs this released first.

Review notes

  • The plugin version was raised by the repo's own sync hook.
  • Mid-session plugin install does not fire SessionStart; whether /setup-space loads without a restart is unchecked.

…r clash

The config is now found from --config, then $SCTX_CONFIG, then the nearest
.sctx.json walking up from the working directory, then the global file. A local
config is no longer shadowed by a global one, and ./config.json in the working
directory is no longer read (set SCTX_CONFIG or rename it to .sctx.json).

includeSpacesFrom: a space in the including file overrides an included space of
the same name instead of throwing, later includes override earlier ones, a
missing include reports E_INCLUDE_NOT_FOUND, and a leading ~ is expanded.

Config load errors carry stable codes (SctxError) so hooks and skills can map
them to a fix.
sctx spaces now checks that the config loads and that each space's path and
schema exist, reporting problems as stable codes with a fix. --json returns the
config path and how it was found, plus the problems, and exits 1 on an error.
A missing config is reported at info level, not as a failure.

sctx spaces add <name> <path> --schema <s> writes to the config found by
walking up, or the one named by --config. When discovery would land on the
global file or on nothing, it requires --config or --global. It will not
rewrite a config that uses JSON5 features; it prints the entry to add instead.
A SessionStart hook runs 'sctx spaces --json' for the session's directory and,
on failure, shows one message with a stable code (E_SCTX_UNAVAILABLE,
E_SCTX_OUTDATED, E_CONFIG_INVALID, E_SPACE_PATH_MISSING, ...) and gives the
agent the fix. With a healthy config it tells the agent which spaces apply; with
none it points at the setup-space skill. A missing Bun is reported by the shell
guard in hooks.json, which also keeps the other hooks silent.

The other hooks treat an unusable 'sctx' answer as 'no spaces' and say nothing,
and pick the config up again as soon as it is fixed. An unexpected error in a
hook becomes one E_HOOK_FAILED message per session with exit 0 instead of a bare
exit 1. Only new validation errors in the Stop hook still block.

The CLI is run from the session's directory, preferring an installed sctx and
otherwise bunx pinned to the plugin's version.
The plugin's patch number moves independently of the package's, so it does not
name a published structured-context release.
… code

setup-space takes a user from no config to one working space and one validated
edit: check the setup, get familiar with the content by sampling, propose a
single space, write it with 'sctx spaces add', summarise the validation gap,
make a guided first edit, and mention the Obsidian plugin after a first-time
setup in a vault. It hands off to the structured-context skill for schema design.

The structured-context skill gains references/troubleshooting.md, one row per
error code with the diagnosis and fix, and its config section now describes
.sctx.json discovery.
Library callers that already know where the config belongs, such as the Obsidian
plugin writing to the vault's .sctx.json, can name it instead of relying on
discovery.
A schema written as an sctx:// URI or without its .json extension was accepted
and only failed later in validate. Every non-URL schema must now resolve to a
file before the space is written.
…n no schema fits

Found by running the skill against three real vaults: agents tried 'spaces add'
without a target first, wrote the schema without its extension, and one wrote a
custom schema mid-setup instead of stopping.
The SessionStart check no longer says anything when no config exists, and no
longer suggests setup-space when a config has no spaces. It still reports
failures once and lists the spaces that apply when it is healthy.

@mindsocket mindsocket left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overcooked and sloppy in places. Lots of docs tightening needed.

Put lessons from these comments into AGENTS.md standards and for docs, a new doc-review kill to avoid this in future (applies to all written content - README, skills, references, docs.

Comment thread docs/config.md Resolved
Comment thread docs/config.md Resolved
Comment thread docs/config.md Resolved
Comment thread plugin/commands/setup-space.md Resolved
Comment thread plugin/scripts/preflight.ts Resolved
Comment thread src/config/write.ts Resolved
Comment thread src/config/index.ts Resolved
Comment thread src/index.ts Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
Move config code into src/config/, trim the public API to what the Obsidian plugin uses,
and make the write-target error independent of the CLI. Tighten the setup-space skill,
troubleshooting reference, README and config docs, and fold the setup-space command into its skill.
@mindsocket

Copy link
Copy Markdown
Owner Author

Addressed all 37 review comments, with a reply on each thread.

  • fc8650b: review fixes (config code moved to src/config/, public API trimmed to what the Obsidian plugin uses, setup-space and troubleshooting tightened, README and config docs in plain language, the /setup-space command folded into its skill)
  • 02cc72f: setup-space says untyped notes are ignored, not failed
  • d261a8b: review lessons in AGENTS.md and a new doc-review skill, in a separate commit

Core tests (845 pass, 15 skipped), hook tests, typecheck and lint pass. The Obsidian branch is updated to match and is still local.

Comment thread src/api.ts Resolved
Comment thread .claude/skills/doc-review/SKILL.md Resolved
Comment thread src/config/write.ts Resolved
Comment thread src/config-write.ts Outdated
const resolved = resolveConfigPath(options.startDir);
if (options.global) {
if (resolved.source === 'override' || resolved.source === 'env') {
throw new SctxError('E_TARGET_REQUIRED', '--global cannot be combined with --config or $SCTX_CONFIG');

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much better, but "Name the config" is awkward. How about "Specify the config file location or global option" instead?

@mindsocket
mindsocket marked this pull request as ready for review October 27, 2026 03:25
@claude

claude Bot commented Oct 27, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.


@mindsocket
mindsocket merged commit bbfc9db into main Oct 27, 2026
2 checks passed
@mindsocket
mindsocket deleted the feat/onboarding-phase1 branch October 27, 2026 05:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant